home *** CD-ROM | disk | FTP | other *** search
- /**
- * @file util.h Utility Functions
- * @ingroup core
- *
- * gaim
- *
- * Gaim is the legal property of its developers, whose names are too numerous
- * to list here. Please refer to the COPYRIGHT file distributed with this
- * source distribution.
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- *
- * @todo Rename the functions so that they live somewhere in the gaim
- * namespace.
- */
- #ifndef _GAIM_UTIL_H_
- #define _GAIM_UTIL_H_
-
- #include <stdio.h>
-
- #include "account.h"
-
- #ifdef __cplusplus
- extern "C" {
- #endif
-
- /**************************************************************************/
- /** @name Base16 Functions */
- /**************************************************************************/
- /*@{*/
-
- /**
- * Converts a string to its base-16 equivalent.
- *
- * @param str The string to convert.
- * @param len The length of the string.
- *
- * @return The base-16 string.
- *
- * @see gaim_base16_decode()
- */
- unsigned char *gaim_base16_encode(const unsigned char *str, int len);
-
- /**
- * Converts a string back from its base-16 equivalent.
- *
- * @param str The string to convert back.
- * @param ret_str The returned, non-base-16 string.
- *
- * @return The length of the returned string.
- *
- * @see gaim_base16_encode()
- */
- int gaim_base16_decode(const char *str, unsigned char **ret_str);
-
- /*@}*/
-
-
- /**************************************************************************/
- /** @name Base64 Functions */
- /**************************************************************************/
- /*@{*/
-
- /**
- * Converts a string to its base-64 equivalent.
- *
- * @param buf The data to convert.
- * @param len The length of the data.
- *
- * @return The base-64 version of @a str.
- *
- * @see gaim_base64_decode()
- */
- unsigned char *gaim_base64_encode(const unsigned char *buf, size_t len);
-
- /**
- * Converts a string back from its base-64 equivalent.
- *
- * @param str The string to convert back.
- * @param ret_str The returned, non-base-64 string.
- * @param ret_len The returned string length.
- *
- * @see gaim_base64_encode()
- */
- void gaim_base64_decode(const char *str, char **ret_str, int *ret_len);
-
- /*@}*/
-
- /**************************************************************************/
- /** @name Quoted Printable Functions */
- /**************************************************************************/
- /*@{*/
-
- /**
- * Converts a quoted printable string back to its readable equivalent.
- *
- * @param str The string to convert back.
- * @param ret_str The returned, readable string.
- * @param ret_len The returned string length.
- */
- void gaim_quotedp_decode (const char *str, char **ret_str, int *ret_len);
-
- /*@}*/
-
- /**************************************************************************/
- /** @name MIME Functions */
- /**************************************************************************/
- /*@{*/
-
- /**
- * Converts a MIME header field string back to its readable equivalent
- * according to RFC 2047. Basically, a header is plain ASCII and can
- * contain any number of sections called "encoded-words." The format
- * of an encoded word is =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?=
- * =? designates the beginning of the encoded-word
- * ?= designates the end of the encoded-word
- * ? segments the encoded word into three pieces. The first piece is
- * the character set, the second piece is the encoding, and the
- * third piece is the encoded text.
- *
- * @param str The string to convert back.
- *
- * @return The readable string.
- */
- char *gaim_mime_decode_field (const char *str);
-
- /*@}*/
-
-
- /**************************************************************************/
- /** @name Date/Time Functions */
- /**************************************************************************/
- /*@{*/
-
- /**
- * Returns the current local time in hour:minute:second form.
- *
- * The returned string is stored in a static buffer, so the result
- * should be g_strdup()'d if it's intended to be used for long.
- *
- * @return The current local time.
- *
- * @see gaim_date_full()
- */
- const char *gaim_date(void);
-
- /**
- * Returns the date and time in human-readable form.
- *
- * The returned string is stored in a static buffer, so the result
- * should be g_strdup()'d if it's intended to be used for long.
- *
- * @return The date and time in human-readable form.
- *
- * @see gaim_date()
- */
- const char *gaim_date_full(void);
-
- /**
- * Builds a time_t from the supplied information.
- *
- * @param year The year.
- * @param month The month.
- * @param day The day.
- * @param hour The hour.
- * @param min The minute.
- * @param sec The second.
- *
- * @return A time_t.
- */
- time_t gaim_time_build(int year, int month, int day, int hour,
- int min, int sec);
-
- /**
- * Parses a timestamp in jabber or ISO8601 format and returns a time_t.
- *
- * @param timestamp The timestamp
- * @param utc Assume UTC if no timezone specified
- *
- * @return A time_t.
- */
- time_t gaim_str_to_time(const char *timestamp, gboolean utc);
-
- /*@}*/
-
-
- /**************************************************************************/
- /** @name Markup Functions */
- /**************************************************************************/
- /*@{*/
-
- /**
- * Finds a HTML tag matching the given name.
- *
- * This locates an HTML tag's start and end, and stores its attributes
- * in a GData hash table. The names of the attributes are lower-cased
- * in the hash table, and the name of the tag is case insensitive.
- *
- * @param needle the name of the tag
- * @param haystack the null-delimited string to search in
- * @param start a pointer to the start of the tag if found
- * @param end a pointer to the end of the tag if found
- * @param attributes the attributes, if the tag was found
- * @return TRUE if the tag was found
- */
- gboolean gaim_markup_find_tag(const char *needle, const char *haystack,
- const char **start, const char **end,
- GData **attributes);
-
- /**
- * Extracts a field of data from HTML.
- *
- * This is a scary function. See protocols/msn/msn.c and
- * protocols/yahoo/yahoo_profile.c for example usage.
- *
- * @param str The string to parse.
- * @param len The size of str.
- * @param dest The destination GString to append the new
- * field info to.
- * @param start_token The beginning token.
- * @param skip The number of characters to skip after the
- * start token.
- * @param end_token The ending token.
- * @param check_value The value that the last character must meet.
- * @param no_value_token The token indicating no value is given.
- * @param display_name The short descriptive name to display for this token.
- * @param is_link TRUE if this should be a link, or FALSE otherwise.
- * @param link_prefix The prefix for the link.
- *
- * @return TRUE if successful, or FALSE otherwise.
- */
- gboolean gaim_markup_extract_info_field(const char *str, int len, GString *dest,
- const char *start_token, int skip,
- const char *end_token, char check_value,
- const char *no_value_token,
- const char *display_name, gboolean is_link,
- const char *link_prefix);
-
- /**
- * Converts HTML markup to XHTML.
- *
- * @param html The HTML markup.
- * @param dest_xhtml The destination XHTML output.
- * @param dest_plain The destination plain-text output.
- */
- void gaim_markup_html_to_xhtml(const char *html, char **dest_xhtml,
- char **dest_plain);
-
- /**
- * Strips HTML tags from a string.
- *
- * @param str The string to strip HTML from.
- *
- * @return The new string without HTML. This must be freed.
- */
- char *gaim_markup_strip_html(const char *str);
-
- /**
- * Adds the necessary HTML code to turn URIs into HTML links in a string.
- *
- * @param str The string to linkify.
- *
- * @return The linkified text.
- */
- char *gaim_markup_linkify(const char *str);
-
- /**
- * Escapes HTML special characters to be displayed literally.
- * For example '&' is replaced by "&" and so on
- *
- * @param html The string in which to escape any HTML special characters
- *
- * @return the text with HTML special characters escaped
- */
- char *gaim_escape_html(const char *html);
-
- /**
- * Unescapes HTML entities to their literal characters.
- * For example "&" is replaced by '&' and so on.
- * Actually only "&", """, "<" and ">" are currently
- * supported.
- *
- * @param html The string in which to unescape any HTML entities
- *
- * @return the text with HTML entities literalized
- */
- char *gaim_unescape_html(const char *html);
-
- /**
- * Returns a newly allocated substring of the HTML UTF-8 string "str".
- * The markup is preserved such that the substring will have the same
- * formatting as original string, even though some tags may have been
- * opened before "x", or may close after "y". All open tags are closed
- * at the end of the returned string, in the proper order.
- *
- * Note that x and y are in character offsets, not byte offsets, and
- * are offsets into an unformatted version of str. Because of this,
- * this function may be sensitive to changes in GtkIMHtml and may break
- * when used with other UI's. libgaim users are encouraged to report and
- * work out any problems encountered.
- *
- * @param str The input NUL terminated, HTML, UTF-8 (or ASCII) string.
- * @param x The character offset into an unformatted version of str to
- * begin at.
- * @param y The character offset (into an unformatted vesion of str) of
- * one past the last character to include in the slice.
- *
- * @return The HTML slice of string, with all formatting retained.
- */
- char *gaim_markup_slice(const char *str, guint x, guint y);
-
- /**
- * Returns a newly allocated string containing the name of the tag
- * located at "tag". Tag is expected to point to a '<', and contain
- * a '>' sometime after that. If there is no '>' and the string is
- * not NUL terminated, this function can be expected to segfault.
- *
- * @param tag The string starting a HTML tag.
- * @return A string containing the name of the tag.
- */
- char *gaim_markup_get_tag_name(const char *tag);
-
- /*@}*/
-
-
- /**************************************************************************/
- /** @name Path/Filename Functions */
- /**************************************************************************/
- /*@{*/
-
- /**
- * Returns the user's home directory.
- *
- * @return The user's home directory.
- *
- * @see gaim_user_dir()
- */
- const gchar *gaim_home_dir(void);
-
- /**
- * Returns the gaim settings directory in the user's home directory.
- *
- * @return The gaim settings directory.
- *
- * @see gaim_home_dir()
- */
- char *gaim_user_dir(void);
-
- /**
- * Define a custom gaim settings directory, overriding the default (user's home directory/.gaim)
- * @param dir The custom settings directory
- */
- void set_gaim_user_dir(const char *dir);
-
- /**
- * Builds a complete path from the root, making any directories along
- * the path which do not already exist.
- *
- * @param path The path you wish to create. Note that it must start
- * from the root or this function will fail.
- * @param mode Unix-style permissions for this directory.
- *
- * @return 0 for success, nonzero on any error.
- */
- int gaim_build_dir(const char *path, int mode);
-
- /**
- * Creates a temporary file and returns a file pointer to it.
- *
- * This is like mkstemp(), but returns a file pointer and uses a
- * pre-set template. It uses the semantics of tempnam() for the
- * directory to use and allocates the space for the file path.
- *
- * The caller is responsible for closing the file and removing it when
- * done, as well as freeing the space pointed to by @a path with
- * g_free().
- *
- * @param path The returned path to the temp file.
- *
- * @return A file pointer to the temporary file, or @c NULL on failure.
- */
- FILE *gaim_mkstemp(char **path);
-
- /**
- * Checks if the given program name is valid and executable.
- *
- * @param program The file name of the application.
- *
- * @return True if the program is runable.
- */
- gboolean gaim_program_is_valid(const char *program);
-
- /**
- * Returns the IP address from a socket file descriptor.
- *
- * @param fd The socket file descriptor.
- *
- * @return The IP address, or @c NULL on error.
- */
- char *gaim_fd_get_ip(int fd);
-
- /*@}*/
-
-
- /**************************************************************************/
- /** @name String Functions */
- /**************************************************************************/
- /*@{*/
-
- /**
- * Normalizes a string, so that it is suitable for comparison.
- *
- * The returned string will point to a static buffer, so if the
- * string is intended to be kept long-term, you <i>must</i>
- * g_strdup() it. Also, calling normalize() twice in the same line
- * will lead to problems.
- *
- * @param account The account the string belongs to.
- * @param str The string to normalize.
- *
- * @return A pointer to the normalized version stored in a static buffer.
- */
- const char *gaim_normalize(const GaimAccount *account, const char *str);
-
- /**
- * Normalizes a string, so that it is suitable for comparison.
- *
- * This is one possible implementation for the PRPL callback
- * function "normalize." It returns a lowercase and UTF-8
- * normalized version of the string.
- *
- * @param account The account the string belongs to.
- * @param str The string to normalize.
- *
- * @return A pointer to the normalized version stored in a static buffer.
- */
- const char *gaim_normalize_nocase(const GaimAccount *account, const char *str);
-
- /**
- * Compares two strings to see if the first contains the second as
- * a proper prefix.
- *
- * @param s The string to check.
- * @param p The prefix in question.
- *
- * @return TRUE if p is a prefix of s, otherwise FALSE.
- */
- gboolean gaim_str_has_prefix(const char *s, const char *p);
-
- /**
- * Compares two strings to see if the second is a proper suffix
- * of the first.
- *
- * @param s The string to check.
- * @param x The suffix in question.
- *
- * @return TRUE if x is a a suffix of s, otherwise FALSE.
- */
- gboolean gaim_str_has_suffix(const char *s, const char *x);
-
- /**
- * Looks for %n, %d, or %t in a string, and replaces them with the
- * specified name, date, and time, respectively.
- *
- * @param str The string that may contain the special variables.
- * @param name The sender name.
- *
- * @return A newly allocated string where the special variables are
- * expanded. This should be g_free'd by the caller.
- */
- gchar *gaim_str_sub_away_formatters(const char *str, const char *name);
-
- /**
- * Duplicates a string and replaces all newline characters from the
- * source string with HTML linebreaks.
- *
- * @param src The source string.
- *
- * @return The new string. Must be g_free'd by the caller.
- */
- gchar *gaim_strdup_withhtml(const gchar *src);
-
- /**
- * Ensures that all linefeeds have a matching carriage return.
- *
- * @param str The source string.
- *
- * @return The string with carriage returns.
- */
- char *gaim_str_add_cr(const char *str);
-
- /**
- * Strips all carriage returns from a string.
- *
- * @param str The string to strip carriage returns from.
- */
- void gaim_str_strip_cr(char *str);
-
- /**
- * Given a string, this replaces one substring with another
- * and returns a newly allocated string.
- *
- * @param string The string from which to replace stuff.
- * @param delimiter The substring you want replaced.
- * @param replacement The substring you want inserted in place
- * of the delimiting substring.
- *
- * @return A new string, after performing the substitution.
- * free this with g_free().
- */
- gchar *gaim_strreplace(const char *string, const char *delimiter,
- const char *replacement);
-
- /**
- * Given a string, this replaces any numerical character references
- * in that string with the corresponding actual utf-8 substrings,
- * and returns a newly allocated string.
- *
- * @param in The string which might contain numerical character references.
- *
- * @return A new string, with numerical character references
- * replaced with actual utf-8, free this with g_free().
- */
- char *gaim_utf8_ncr_decode(const char *in);
-
- /**
- * Given a string, this replaces one substring with another
- * ignoring case and returns a newly allocated string.
- *
- * @param string The string from which to replace stuff.
- * @param delimiter The substring you want replaced.
- * @param replacement The substring you want inserted in place
- * of the delimiting substring.
- *
- * @return A new string, after performing the substitution.
- * free this with g_free().
- */
- gchar *gaim_strcasereplace(const char *string, const char *delimiter,
- const char *replacement);
-
- /**
- * This is like strstr, except that it ignores ASCII case in
- * searching for the substring.
- *
- * @param haystack The string to search in.
- * @param needle The substring to find.
- *
- * @return the location of the substring if found, or NULL if not
- */
- const char *gaim_strcasestr(const char *haystack, const char *needle);
-
- /**
- * Returns a string representing a filesize in the appropriate
- * units (MB, KB, GB, etc.)
- *
- * @param size The size
- *
- * @return The string in units form. This must be freed.
- */
- char *gaim_str_size_to_units(size_t size);
-
- /**
- * Converts seconds into a human-readable form.
- *
- * @param sec The seconds.
- *
- * @return A human-readable form, containing days, hours, minutes, and
- * seconds.
- */
- char *gaim_str_seconds_to_string(guint sec);
-
- /**
- * Converts a binary string into a NUL terminated ascii string,
- * replacing nonascii characters and characters below SPACE (including
- * NUL) into \\xyy, where yy are two hex digits. Also backslashes are
- * changed into two backslashes (\\\\). The returned, newly allocated
- * string can be outputted to the console, and must be g_free()d.
- *
- * @param binary A string of random data, possibly with embedded NULs
- * and such.
- * @param len The length in bytes of the input string. Must not be 0.
- *
- * @return A newly allocated ASCIIZ string.
- */
- char *gaim_str_binary_to_ascii(const unsigned char *binary, guint len);
- /*@}*/
-
-
- /**************************************************************************/
- /** @name URI/URL Functions */
- /**************************************************************************/
- /*@{*/
-
- /**
- * Parses a URL, returning its host, port, file path, username and password.
- *
- * The returned data must be freed.
- *
- * @param url The URL to parse.
- * @param ret_host The returned host.
- * @param ret_port The returned port.
- * @param ret_path The returned path.
- * @param ret_user The returned username.
- * @param ret_passwd The returned password.
- */
- gboolean gaim_url_parse(const char *url, char **ret_host, int *ret_port,
- char **ret_path, char **ret_user, char **ret_passwd);
-
- /**
- * Fetches the data from a URL, and passes it to a callback function.
- *
- * @param url The URL.
- * @param full TRUE if this is the full URL, or FALSE if it's a
- * partial URL.
- * @param user_agent The user agent field to use, or NULL.
- * @param http11 TRUE if HTTP/1.1 should be used to download the file.
- * @param cb The callback function.
- * @param data The user data to pass to the callback function.
- */
- void gaim_url_fetch(const char *url, gboolean full,
- const char *user_agent, gboolean http11,
- void (*cb)(void *, const char *, size_t),
- void *data);
- /**
- * Decodes a URL into a plain string.
- *
- * This will change hex codes and such to their ascii equivalents.
- *
- * @param str The string to translate.
- *
- * @return The resulting string.
- */
- const char *gaim_url_decode(const char *str);
-
- /**
- * Encodes a URL into an escaped string.
- *
- * This will change non-alphanumeric characters to hex codes.
- *
- * @param str The string to translate.
- *
- * @return The resulting string.
- */
- const char *gaim_url_encode(const char *str);
-
- /**
- * Checks if the given email address is syntactically valid.
- *
- * @param address The email address to validate.
- *
- * @return True if the email address is syntactically correct.
- */
- gboolean gaim_email_is_valid(const char *address);
-
- /**
- * This function extracts a list of URIs from the a "text/uri-list" string
- * It was "borrowed" from gnome_uri_list_extract_uris
- *
- * @param uri_list an uri-list in the standard format.
- *
- * @return a GList containing strings allocated with g_malloc that have been
- * splitted from uri-list.
- */
- GList* gaim_uri_list_extract_uris (const gchar* uri_list);
-
- /**
- * This function extracts a list of filenames from the a "text/uri-list" string
- * It was "borrowed" from gnome_uri_list_extract_filenames
- *
- * @param uri_list an uri-list in the standard format.
- *
- * @return a GList containing strings allocated with g_malloc that contain the
- * filenames in the uri-list. Note that unlike gaim_uri_list_extract_uris()
- * function, this will discard any non-file uri from the result value.
- */
- GList* gaim_uri_list_extract_filenames (const gchar* uri_list);
-
- /*@}*/
-
- /**************************************************************************
- * UTF8 String Functions
- **************************************************************************/
- /*@{*/
-
- /**
- * Attempts to convert a string to UTF-8 from an unknown encoding.
- *
- * This function checks the locale and tries sane defaults.
- *
- * @param str The source string.
- *
- * @return The UTF-8 string, or @c NULL if it could not be converted.
- */
- gchar *gaim_utf8_try_convert(const char *str);
-
- /**
- * Salvages the valid UTF-8 characters from a string, replacing any
- * invalid characters with a filler character (currently hardcoded to
- * '?').
- *
- * @param str The source string.
- *
- * @return A valid UTF-8 string.
- */
- gchar *gaim_utf8_salvage(const char *str);
-
- /**
- * Compares two UTF-8 strings.
- *
- * @param a The first string.
- * @param b The second string.
- *
- * @return -1 if @a is less than @a b.
- * 0 if @a is equal to @a b.
- * 1 if @a is greater than @a b.
- */
- int gaim_utf8_strcasecmp(const char *a, const char *b);
-
- /**
- * Checks for messages starting with "/me "
- *
- * @param message The message to check
- * @param len The message length, or -1
- *
- * @return TRUE if it starts with /me, and it has been removed, otherwise FALSE
- */
- gboolean gaim_message_meify(char *message, size_t len);
-
- /**
- * Removes the underscore characters from a string used identify the mnemonic
- * character.
- *
- * @param in The string to strip
- *
- * @return The stripped string
- */
- char *gaim_text_strip_mnemonic(const char *in);
-
- /*@}*/
-
- /**
- * Adds 8 to something.
- *
- * Blame SimGuy.
- *
- * @param x The number to add 8 to.
- *
- * @return x + 8
- */
- #define gaim_add_eight(x) ((x)+8)
-
- /**
- * Does the reverse of gaim_escape_filename
- *
- * This will change hex codes and such to their ascii equivalents.
- *
- * @param str The string to translate.
- *
- * @return The resulting string.
- */
- const char *gaim_unescape_filename(const char *str);
-
- /**
- * Escapes filesystem-unfriendly characters from a filename
- *
- * @param str The string to translate.
- *
- * @return The resulting string.
- */
- const char *gaim_escape_filename(const char *str);
-
- #ifdef __cplusplus
- }
- #endif
-
- #endif /* _GAIM_UTIL_H_ */
-